/**
 * Vue Router 实例创建和配置
 * 使用 Vue Router 4.4.5 版本
 */

// 导入 Vue Router 的相关函数
import { createRouter, createWebHistory } from "vue-router";
// 导入自定义的路由配置数组
import { routes } from "@/router/router";

/**
 * 创建 Vue Router 实例
 * 
 * @description
 * - createRouter: 创建路由实例的核心函数
 * - createWebHistory: 使用 HTML5 History 模式，需要服务器配置支持
 *   替代方案: createWebHashHistory() 使用 hash 模式，无需服务器配置
 *   替代方案: createMemoryHistory() SSR 场景使用
 */
const router = createRouter({
    /**
     * 路由历史模式配置
     * 
     * @param {string} base - 可选的基路径，默认为 '/'
     * @example
     * createWebHistory('/admin/') // 应用部署在 /admin/ 子路径下
     */
    history: createWebHistory(),
    
    /**
     * 路由配置数组
     * 
     * @type {Array<RouteRecordRaw>}
     * @structure
     * [
     *   {
     *     path: '/',           // 路由路径
     *     name: 'Home',        // 路由名称（可选，但推荐使用）
     *     component: Home,     // 路由组件
     *     meta: {},            // 路由元信息
     *     children: []         // 嵌套路由
     *   }
     * ]
     */
    routes,
    
    /**
     * 可选的滚动行为配置（示例，当前未使用）
     * 
     * @example
     * scrollBehavior(to, from, savedPosition) {
     *   // 返回顶部
     *   if (to.hash) {
     *     return { el: to.hash, behavior: 'smooth' }
     *   } else if (savedPosition) {
     *     return savedPosition
     *   } else {
     *     return { top: 0 }
     *   }
     * }
     */
    
    /**
     * 是否使用严格模式（示例，当前未使用）
     * 
     * @type {boolean}
     * @description 严格模式下，路径末尾的斜杠会被认为是不同的路径
     * @example
     * strict: true // /home 和 /home/ 被视为不同路径
     */
});

// 导出路由实例，供 Vue 应用使用
export default router;

/**
 * 使用说明：
 * 
 * 1. 在 main.js 中注册：
 *    import router from './router'
 *    app.use(router)
 * 
 * 2. 在组件中使用：
 *    - 模板中：<router-link to="/">Home</router-link>
 *    - 模板中：<router-view />
 *    - 组合式API：import { useRouter, useRoute } from 'vue-router'
 * 
 * 3. 路由守卫示例：
 *    router.beforeEach((to, from, next) => {
 *      // 身份验证逻辑
 *      next()
 *    })
 * 
 * 4. 路由元信息使用：
 *    // 在路由配置中添加 meta 字段
 *    // 在导航守卫中访问：to.meta.requiresAuth
 */